ScriptLink technical overview

By Tim Hoffman, Technical Director, Momentum

Until now, there has been no easy way for Newton developers to 
interact with information on other platforms. Whilst the Newton 
Connection Kit offers import and export facilities, it is clearly 
aimed at the personal user. For the developer who wishes to query a 
database or update a file from the Newton in realtime, the 
alternative has been the painful process of building a solution from 
scratch.

For the Newton developers working with Macintosh based systems, there 
is now a solution. ScriptLink offers Newton developers a flexible 
mechanism for controlling a server Macintosh using AppleScript. 
Combining the flexibility of AppleScript with the mobile computing 
power of the Newton, ScriptLink enables developers to quickly build 
customised solutions using off the shelf software packages. 
ScriptLink is compatible with industry standard wired and wireless 
AppleTalk networks.

The ScriptLink Developer Kit is based on a powerful client server 
architecture. The Macintosh based ScriptLink Server provides a 
secure, multi-user environment in which AppleScript commands are 
executed. The Newton based ScriptLink Client provides a high level 
interface for developers of Newton applications, removing the 
requirement to work directly with low level communications protocols. 
Using ScriptLink, developers can eliminate the need to create 
customised server software for each application, dramatically 
reducing overall development time.

By using the power of AppleScript with third party applications, 
ScriptLink enables easy access to data on other platforms. For 
example, using an AppleScript database gateway, a Newton application 
can access information in an Oracle database residing on a Unix 
server, or across a Novell network to data used on a Windows system.

Potential applications

Potential applications range from simple data transfer to vertical 
market data capture and retrieval applications. Using the wide range 
of AppleScript-aware applications available for the Macintosh, any 
Newton developer can easily add remote communications, database 
access and other facilities to their Newton application. 

Beta testers have reported excellent results using ScriptLink to 
control applications such as FileMaker Pro, 4th Dimension, HyperCard 
and custom developed software.

Prerequisites

To use ScriptLink a Macintosh server with the following minimum 
specifications is required.

1mb free RAM
1mb disk space
AppleTalk network connection
System 7.1
AppleScript 1.1

Generally, a 68040 based Macintosh server is recommended for the best 
possible performance. ScriptLink is compatible with PowerMacintosh 
systems. 

The ScriptLink Client is a 30k Newton application which is installed 
onto each Newton. The client supports all current Newton products. 
Newton system v1.1 or later is recommended. An AppleTalk network 
connection is required to communicate with the ScriptLink Server.

Developers should be familiar with both the Newton Toolkit and 
AppleScript. Access to the Newton Toolkit v1.0.1 is required and 
access to the AppleScript Developer Kit v1.1 is highly recommended.

How the ScriptLink Server works

The ScriptLink Server provides a controlled environment for the 
execution of AppleScript by multiple Newton clients. The status 
window displays the name and network address of connected users, and 
an onscreen diagnostics facility allows you to see exactly what is 
happening at any time. An idle timeout facility allows you to 
automatically logout users if they are inactive for a specified 
period of time.

A variety of authentication options allows the developer to apply as 
much or as little security as needed for different applications. 
Authentication options include no authentication, a simple 
username/password combination or a customised system using 
AppleScript supplied by the developer. Custom authentication systems 
could include access to other servers to validate usernames as 
required.

The server can produce full logs showing all logins and logouts. A 
diagnostics option assists the developer by logging the text of all 
AppleScripts executed and results returned by the server.

Using ScriptLink with your Newton application

The operation of ScriptLink is fully asynchronous. Whilst waiting for 
a connection to occur or AppleScript code to be executed, the Newton 
application may continue its own processing as required. The 
developer interacts with ScriptLink using three main calls.

SLConnect opens a connection to the ScriptLink Server, specifying a 
network address, username and password.

SLDisconnect closes the connection to the ScriptLink Server.

SLSendScript sends an AppleScript to be executed.

Two further calls provide information about your current connection 
to the server at any time. SLTransOutstanding allows the application 
to check  if the current script is completed. SLConnectionStatus 
returns the status of the connection to the server

ScriptLink uses the following callbacks inside the Newton application 
to indicate the completion of a transaction. 

SLConnectDone indicates the connection has been opened.

SLDisconnectDone indicates the connection has been closed.

SLScriptReturned is called when data is returned as the result of the 
execution of an AppleScript.

An example application

After designing your Newton application and installing the required 
Macintosh applications,  the developer can develop a standalone 
AppleScript to perform the required functions and test it using the 
Script Editor. This script will later be used inside the Newton 
application. 

The developer can then create a new project in the Newton Toolkit and 
design the appropriate views for the application. ScriptLink will 
require the following callback slots defined in your application:

SLConnectDone
SLDisconnectDone
SLScriptReturned

When your application needs to connect to ScriptLink, you first need 
to check that the client is loaded, then clone a copy of the 
ScriptLink Client for your own use.

In this example, we use sl as the handle to the cloned copy of 
ScriptLink.

if sl = nil then
   if HasSlot(GetRoot(),'|ScriptLink:MOMENTUM|) then           
	sl:=Clone(GetRoot().|ScriptLink:MOMENTUM|._proto);
else begin                 
	EnsureInternal(
		GetRoot():Notify(kNotifyAlert, kApptitle, 
                     "ScriptLink Client not loaded"));
end;

Next, choose the ScriptLink Server which you wish to connect to over 
the network. This can be achieved via a hardcoded AppleTalk address 
or by using the Newton chooser as shown below. 

GetRoot().NetChooser:openNetChooser(nil,
	"=:ScriptLink@",nil,self,
	"Connect","ScriptLink Server","");

The Newton chooser will then call a method defined in your 
application called NetworkChooserDone.  Once an address is 
successfully defined, use SLConnect to connect to the ScriptLink 
Server and test for a successfully initialised connection as follows:

if sl:SLConnect({caller: base,
		server: server,	
		username:"peter",
		password:"test",	
		title: "Tester",
		debug: nil,		
		poweroff: nil
		}) 

	then EnsureInternal(
		GetRoot():Notify(kNotifyAlert, kApptitle, 
                     "Connection Initialisation Failed!"));

On login to the server the callback SLConnectDone will be invoked, 
enabling the application to indicate a successful or unsuccessful 
login.

Once SLConnectDone has been called, send the first AppleScript to the 
ScriptLink Server using SLSendScript. Special characters need to be 
escaped as shown below. 

TestScript:="set result to \"hello world\"\n";

sl:SLSendScript({script: TestScript , client_tag: nil});

Alternatively, you could define an entire text slot as an AppleScript 
code fragment and send this. 

The application will be notified of the result of the AppleScript by 
using the SLScriptReturned callback. SLScriptReturned takes one 
argument.

func(x)	//SLScriptReturned

begin
	if x.status = 0 then    
	begin
		:SLSetStatus("Received - [" & x.data & "]");   
	end
	else if x.status = 4 then 
	begin
		EnsureInternal(GetRoot():Notify(
		kNotifyAlert, kApptitle, 
		"Script Error returned from ScriptLink Server"))
	end;
end

Finally, close the connection to the ScriptLink Server using 
SLDisconnect.

sl:SLDisconnect(nil);

What is in the ScriptLink Developer Kit?

Full developer documentation and a range of sample applications are 
included in the ScriptLink Developer Kit. The samples use the 
Scriptable Text Editor and FileMaker Pro to illustrate the basic 
concepts of ScriptLink.

Availability

The ScriptLink Developer Kit will be available as of August 1st. 
Additional copies of  the ScriptLink Server and Client software will 
also be available for use in end user sites where applications are 
deployed. The ScriptLink technology can be licensed for inclusion 
with commercial software.

Plans for future releases of ScriptLink include a PowerPC native 
version of the server, support for serial, modem and infra-red 
connections, and support for multiple OSA compliant scripting 
languages.

Distributors

ScriptLink is available from the following companies.

Momentum Pty Ltd
Perth, Australia
Phone +61 9 483 2649
Fax +61 9 227 5447
Internet momentum@dialix.oz.au
AppleLink MOMENTUM.AUS

Momentum Pty Ltd is a privately held Western Australian company that 
develops, markets and distributes mobile computing technologies. 
ScriptLink is the first in a family of Newton connectivity solutions 
from Momentum.

Creative Digital Systems
San Francisco, USA
Phone (415) 621 4252
Fax (415) 621 4922
Internet cds@netcom.com
AppleLink CDS.SEM

Creative Digital Systems is the publisher of PIE Developers magazine, 
a technical journal for Newton developers, and the leading publisher 
and distributor of Newton developer tools.

---

ScriptLink is a trademark of Momentum Pty Ltd. Macintosh is a 
registered trademark of Apple Computer, Inc.  AppleScript, AppleTalk, 
MessagePad and Newton are trademarks of Apple Computer, Inc. All 
other corporate, brand, product and service names are trademarks of 
their respective holders. Mention of third party products is for 
informational purposes only and constitutes neither an endorsement 
nor a recommendation.

Copyright 1994 Momentum.



